Workflow Human Template

The Workflow Human template demonstrates how BindAI can pause workflow execution by creating a HumanTask and placing the workflow context into a waiting state. The HumanTaskNode is designed for human-in-the-loop workflows where an external interface or application can inspect the created task and handle the human interaction.

Purpose

This template demonstrates how to:

create a human task
associate the task with a workflow instance
associate the task with a workflow node
store the task in the workflow context
pause workflow execution using the waiting state
configure an optional assignee
configure an optional form

The node provides the workflow-engine side of human interaction. The actual user interface and task-completion mechanism are external to the node.

Workflow Structure

A workflow can place a Human Task node between normal workflow nodes.

Start

↓

Agent

↓

Human Task

↓

Waiting

When the Human Task node executes, it creates a task and marks the workflow context as waiting.

Human Task Node

The implementation is provided by HumanTaskNode. Conceptually:

HumanTaskNode(
    node_id="approval",
    assignee="manager",
    form="approval-form",
)

The node accepts four configuration values:

Parameter	Description
`node_id`	Identifier of the workflow node
`assignee`	Optional identifier of the person assigned to the task
`form`	Optional form identifier
`name`	Optional workflow node name

Task Creation

When the node executes, it creates a new HumanTask. The task receives a generated UUID.

HumanTaskNode

↓

Generate Task ID

↓

Create HumanTask

The task records:

task ID
workflow instance ID
node ID
creation timestamp

Conceptually:

HumanTask(
    id=<generated UUID>,
    workflow_instance=context.instance.id,
    node_id=self.id,
    created_at=datetime.utcnow(),
)

Workflow Context

The newly created task is stored in the workflow context.

HumanTaskNode

↓

HumanTask

↓

context.task

This allows the currently executing workflow instance to expose the task through its runtime context.

Waiting State

After creating the task, the node sets:

context.waiting = True

The workflow therefore enters a waiting state.

Execute Human Task

↓

Create Task

↓

Store in context.task

↓

context.waiting = True

↓

Workflow Waiting

The executor can use this state to stop normal execution until the workflow is resumed.

External Task Handling

HumanTaskNode does not provide a user interface. The task can instead be consumed by an external system such as:

a web application
an administrative dashboard
an approval interface
a mobile application
an internal task-management system

The workflow package is responsible for creating the task and entering the waiting state. The external application is responsible for presenting the task to a human.

Assignee

A Human Task may optionally specify an assignee. Example:

HumanTaskNode(
    node_id="approval",
    assignee="manager",
)

The assignee is stored on the node as:

self.assignee = assignee

The implementation does not itself perform assignment or notification.

Form

A Human Task may also specify an optional form identifier. Example:

HumanTaskNode(
    node_id="review",
    form="review-form",
)

The form value is stored on the node:

self.form = form

The node does not render or process the form itself.

Task Lifecycle

The implemented lifecycle is limited to task creation and entering the waiting state.

Human Task Node

↓

Create HumanTask

↓

Store task in context

↓

Set waiting = True

↓

Workflow waits

Task completion and workflow resumption are handled outside the HumanTaskNode implementation.

Workflow Instance Association

Every created task is associated with the currently executing workflow instance.

workflow_instance=context.instance.id

This allows external systems to identify which workflow execution produced the task. Conceptually:

Workflow Instance

↓

HumanTaskNode

↓

HumanTask

↓

Workflow Instance ID

Node Association

The generated task also records the ID of the node that created it.

node_id=self.id

This allows the task to be associated with the specific Human Task node within the workflow.

Unique Task IDs

Every execution creates a new task ID using Python’s UUID generator.

str(uuid.uuid4())

Therefore, each created task receives a unique identifier.

Human Task Execution 1
        ↓
Task ID A

Human Task Execution 2
        ↓
Task ID B

Serialization

HumanTaskNode extends the normal workflow-node serialization. Its serialized representation includes:

{
    "assignee": ...,
    "form": ...,
}

This allows the optional human-task configuration to be persisted with the workflow definition.

Loading Configuration

The node can restore its human-task configuration from serialized data. The implementation reads:

self.assignee = data.get("assignee")
self.form = data.get("form")

If either value is missing, it remains None.

Human + AI Workflow

A common workflow pattern is:

AI Agent

↓

Human Task

↓

Waiting

For example, an AI agent may generate a document and then create a human task for review. The Human Task node does not perform the review itself. It creates the task that an external system can present to the reviewer.

Human Tasks vs Conditions

These nodes serve different purposes.

Human Task	Condition
Creates a human task	Evaluates a predicate
Stores task in context	Selects an execution path
Sets workflow waiting state	Continues execution
External human interaction	Automatic decision

A workflow can combine both patterns. For example:

Human Task

↓

Waiting

↓

Human Decision

↓

Condition

↓

Approved / Rejected

The exact decision and resume mechanism depends on the surrounding application and workflow implementation.

Human Tasks vs Loops

Human Tasks and loops also have different purposes.

Human Task	Loop
Waits for external human interaction	Repeats workflow logic
Creates a `HumanTask`	Evaluates a predicate
Sets `context.waiting`	Changes `context.current_node`
Potentially long-running	Iterative execution

A loop repeats automatically according to workflow state, while a Human Task introduces an external waiting point.

Example

A document-review workflow might look like:

Start

↓

Agent

↓

Human Review

↓

Waiting

When the Human Review node executes:

HumanTask created
        ↓
context.task = task
        ↓
context.waiting = True

An external application can then inspect the task and provide the human interaction.

Important Implementation Boundary

The HumanTaskNode implementation does not:

approve a task
reject a task
collect form responses
notify an assignee
render a form
mark a task as completed
resume the workflow

Those responsibilities belong to surrounding application or execution infrastructure. The node’s implemented responsibility is:

Create Task
     ↓
Store Task
     ↓
Enter Waiting State

Best Practices

Provide a meaningful node_id.
Use assignee when an external system needs an intended task owner.
Use form to associate a task with an external form definition.
Keep task presentation outside the workflow node.
Treat context.task as the runtime task created by the node.
Ensure the surrounding application provides a mechanism for handling waiting workflows.
Keep human interaction logic separate from workflow-definition logic.

Summary

The Workflow Human template demonstrates how BindAI introduces a human interaction point into workflow execution. HumanTaskNode creates a uniquely identified HumanTask, associates it with the current workflow instance and node, stores it in context.task, and sets context.waiting = True. The node does not implement approval, rejection, form handling, notifications, or workflow resumption. Those behaviors are provided by the surrounding workflow and application infrastructure.

Getting Started

Core

Tools

Memory

Knowledge

Connections

Automation

Workflows

Projects

Templates

Roadmap

API Reference

08.5 workflow human

Workflow Human Template

Purpose

Workflow Structure

Human Task Node

Task Creation

Workflow Context

Waiting State

External Task Handling

Assignee

Form

Task Lifecycle

Workflow Instance Association

Node Association

Unique Task IDs

Serialization

Loading Configuration

Human + AI Workflow

Human Tasks vs Conditions

Human Tasks vs Loops

Example

Important Implementation Boundary

Best Practices

Summary

​Workflow Human Template

​Purpose

​Workflow Structure

​Human Task Node

​Task Creation

​Workflow Context

​Waiting State

​External Task Handling

​Assignee

​Form

​Task Lifecycle

​Workflow Instance Association

​Node Association

​Unique Task IDs

​Serialization

​Loading Configuration

​Human + AI Workflow

​Human Tasks vs Conditions

​Human Tasks vs Loops

​Example

​Important Implementation Boundary

​Best Practices

​Summary

Workflow Human Template

Purpose

Workflow Structure

Human Task Node

Task Creation

Workflow Context

Waiting State

External Task Handling

Assignee

Form

Task Lifecycle

Workflow Instance Association

Node Association

Unique Task IDs

Serialization

Loading Configuration

Human + AI Workflow

Human Tasks vs Conditions

Human Tasks vs Loops

Example

Important Implementation Boundary

Best Practices

Summary